#region license
/*
 * Copyright (C) 2007 CchenSoft.com
 * 
 * This library is free software; you can redistribute it and/or modify it 
 * under the terms of the GNU Lesser General Public License 2.1 or later, as
 * published by the Free Software Foundation. See the included License.txt
 * or http://www.gnu.org/copyleft/lesser.html for details.
 * 
 * Author: Billy Zhang
 */
#endregion

using System;
using System.Collections;
using System.Collections.Generic;

using CchenSoft.Workflow.Query;

namespace CchenSoft.Workflow.Spi
{
    /**
     * Interface for pluggable workflow stores configured in osworkflow.xml.
     * Only one instance of a workflow store is ever created, meaning that
     * if your persistence connections (such as java.sql.Connection) time out,
     * it would be un-wise to use just one Connection for the entire object.
     */

    public interface IWorkflowStore
    {
        //~ Methods ////////////////////////////////////////////////////////////////

        /**
         * Set the state of the workflow instance.
         * @param entryId The workflow instance id.
         * @param state The state to move the workflow instance to.
         */
        void SetEntryState(long entryId, int state);

        /**
         * Persists a step with the given parameters.
         *
         * @param entryId The workflow instance id.
         * @param stepId the ID of the workflow step associated with this new
         *               Step (not to be confused with the step primary key)
         * @param owner the owner of the step
         * @param startDate the start date of the step
         * @param status the status of the step
         * @param previousIds the previous step IDs
         * @return a representation of the workflow step persisted
         */
        IStep CreateCurrentStep(long entryId, int stepId, string owner, DateTime startDate, DateTime? dueDate, string status, long[] previousIds);

        /**
         * Persists a new workflow entry that has <b>not been initialized</b>.
         *
         * @param workflowName the workflow name that this entry is an instance of
         * @return a representation of the workflow instance persisted
         */
        IWorkflowEntry CreateEntry(string workflowName);

        /**
         * Returns a list of all current steps for the given workflow instance ID.
         *
         * @param entryId The workflow instance id.
         * @return a List of Steps
         * @see com.opensymphony.workflow.spi.Step
         */
        IList<IStep> FindCurrentSteps(long entryId);

        /**
         * Pulls up the workflow entry data for the entry ID given.
         *
         * @param entryId The workflow instance id.
         * @return a representation of the workflow instance persisted
         */
        IWorkflowEntry FindEntry(long entryId);

        /**
         * Returns a list of all steps that are finished for the given workflow instance ID.
         *
         * @param entryId The workflow instance id.
         * @return a List of Steps
         * @see com.opensymphony.workflow.spi.Step
         */
        IList<IStep> FindHistorySteps(long entryId);

        /**
         * Called once when the store is first created.
         *
         * @param props properties set in osworkflow.xml
         */
        void Init(IDictionary props);

        /**
         * Mark the specified step as finished.
         * @param step the step to finish.
         * @param actionId The action that caused the step to finish.
         * @param finishDate the date when the step was finished.
         * @param status The status to set the finished step to.
         * @param caller The caller that caused the step to finish.
         * @return the finished step
         */
        IStep MarkFinished(IStep step, int actionId, DateTime? finishDate, string status, string caller);

        /**
         * Called when a step is finished and can be moved to workflow history.
         *
         * @param step the step to be moved to workflow history
         */
        void MoveToHistory(IStep step);

        /**
         * @deprecated use {@link WorkflowStore#query(WorkflowExpressionQuery)} instead.
         * @param query the query to use
         * @return a List of workflow instance ID's
         */
        IList<long> Query(WorkflowQuery query);

        /**
         * @param query the query to use
         * @return a List of workflow instance ID's
         */
        IList<long> Query(WorkflowExpressionQuery query);

        int BeginTransaction();

        void RollbackTransaction();

        void CommitTransaction();
    }
}
